home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_perl.idb / usr / freeware / catman / p_man / cat3 / Net::Ping.Z / Net::Ping
Encoding:
Text File  |  1998-10-28  |  8.1 KB  |  265 lines
  1.  
  2.  
  3.  
  4.      NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.       Net::Ping - check a remote host for reachability
  10.  
  11.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.           use Net::Ping;
  13.  
  14.           $p = Net::Ping->new();
  15.           print "$host is alive.\n"    if $p->ping($host);
  16.           $p->close();
  17.  
  18.           $p = Net::Ping->new("icmp");
  19.           foreach $host (@host_array)
  20.           {
  21.           print    "$host is ";
  22.           print    "NOT " unless $p->ping($host, 2);
  23.           print    "reachable.\n";
  24.           sleep(1);
  25.           }
  26.           $p->close();
  27.  
  28.           $p = Net::Ping->new("tcp", 2);
  29.           while ($stop_time    > time())
  30.           {
  31.           print    "$host not reachable ",    scalar(localtime()), "\n"
  32.               unless $p->ping($host);
  33.           sleep(300);
  34.           }
  35.           undef($p);
  36.  
  37.           #    For backward compatibility
  38.           print "$host is alive.\n"    if pingecho($host);
  39.  
  40.  
  41.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  42.       This module contains methods to test the reachability    of
  43.       remote hosts on a network.  A    ping object is first created
  44.       with optional    parameters, a variable number of hosts may be
  45.       pinged multiple times    and then the connection    is closed.
  46.  
  47.       You may choose one of    three different    protocols to use for
  48.       the ping.  With the "tcp" protocol the _p_i_n_g()    method
  49.       attempts to establish    a connection to    the remote host's echo
  50.       port.     If the    connection is successfully established,    the
  51.       remote host is considered reachable.    No data    is actually
  52.       echoed.  This    protocol does not require any special
  53.       privileges but has higher overhead than the other two
  54.       protocols.
  55.  
  56.       Specifying the "udp" protocol    causes the _p_i_n_g() method to
  57.       send a udp packet to the remote host's echo port.  If    the
  58.       echoed packet    is received from the remote host and the
  59.       received packet contains the same data as the    packet that
  60.  
  61.  
  62.  
  63.      Page 1                        (printed 10/23/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))
  71.  
  72.  
  73.  
  74.       was sent, the    remote host is considered reachable.  This
  75.       protocol does    not require any    special    privileges.
  76.  
  77.       If the "icmp"    protocol is specified, the _p_i_n_g() method sends
  78.       an icmp echo message to the remote host, which is what the
  79.       UNIX ping program does.  If the echoed message is received
  80.       from the remote host and the echoed information is correct,
  81.       the remote host is considered    reachable.  Specifying the
  82.       "icmp" protocol requires that    the program be run as root or
  83.       that the program be setuid to    root.
  84.  
  85.       FFFFuuuunnnnccccttttiiiioooonnnnssss
  86.  
  87.       Net::Ping->new([$proto [, $def_timeout [, $bytes]]]);
  88.           Create a new ping    object.     All of    the parameters are
  89.           optional.     $proto    specifies the protocol to use when
  90.           doing a ping.  The current choices are "tcp", "udp" or
  91.           "icmp".  The default is "udp".
  92.  
  93.           If a default timeout ($def_timeout) in seconds is
  94.           provided,    it is used when    a timeout is not given to the
  95.           _p_i_n_g() method (below).  The timeout must be greater than
  96.           0    and the    default, if not    specified, is 5    seconds.
  97.  
  98.           If the number of data bytes ($bytes) is given, that many
  99.           data bytes are included in the ping packet sent to the
  100.           remote host. The number of data bytes is ignored if the
  101.           protocol is "tcp".  The minimum (and default) number of
  102.           data bytes is 1 if the protocol is "udp" and 0
  103.           otherwise.  The maximum number of    data bytes that    can be
  104.           specified    is 1024.
  105.  
  106.       $p->ping($host [, $timeout]);
  107.           Ping the remote host and wait for    a response.  $host can
  108.           be either    the hostname or    the IP number of the remote
  109.           host.  The optional timeout must be greater than 0
  110.           seconds and defaults to whatever was specified when the
  111.           ping object was created.    If the hostname    cannot be
  112.           found or there is    a problem with the IP number, undef is
  113.           returned.     Otherwise, 1 is returned if the host is
  114.           reachable    and 0 if it is not.  For all practical
  115.           purposes,    undef and 0 and    can be treated as the same
  116.           case.
  117.  
  118.       $p->close();
  119.           Close the    network    connection for this ping object.  The
  120.           network connection is also closed    by "undef $p".    The
  121.           network connection is automatically closed if the    ping
  122.           object goes out of scope (e.g. $p    is local to a
  123.           subroutine and you leave the subroutine).
  124.  
  125.  
  126.  
  127.  
  128.  
  129.      Page 2                        (printed 10/23/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))
  137.  
  138.  
  139.  
  140.       pingecho($host [, $timeout]);
  141.           To provide backward compatibility    with the previous
  142.           version of Net::Ping, a _p_i_n_g_e_c_h_o() subroutine is
  143.           available    with the same functionality as before.
  144.           _p_i_n_g_e_c_h_o() uses the tcp protocol.     The return values and
  145.           parameters are the same as described for the _p_i_n_g()
  146.           method.  This subroutine is obsolete and may be removed
  147.           in a future version of Net::Ping.
  148.  
  149.      WWWWAAAARRRRNNNNIIIINNNNGGGG
  150.       _p_i_n_g_e_c_h_o() or    a ping object with the tcp protocol use
  151.       _a_l_a_r_m() to implement the timeout.  So, don't use _a_l_a_r_m() in
  152.       your program while you are using _p_i_n_g_e_c_h_o() or a ping    object
  153.       with the tcp protocol.  The udp and icmp protocols do    not
  154.       use _a_l_a_r_m() to implement the timeout.
  155.  
  156.      NNNNOOOOTTTTEEEESSSS
  157.       There    will be    less network overhead (and some    efficiency in
  158.       your program)    if you specify either the udp or the icmp
  159.       protocol.  The tcp protocol will generate 2.5    times or more
  160.       traffic for each ping    than either udp    or icmp.  If many
  161.       hosts    are pinged frequently, you may wish to implement a
  162.       small    wait (e.g. 25ms    or more) between each ping to avoid
  163.       flooding your    network    with packets.
  164.  
  165.       The icmp protocol requires that the program be run as    root
  166.       or that it be    setuid to root.     The tcp and udp protocols do
  167.       not require special privileges, but not all network devices
  168.       implement the    echo protocol for tcp or udp.
  169.  
  170.       Local    hosts should normally respond to pings within
  171.       milliseconds.     However, on a very congested network it may
  172.       take up to 3 seconds or longer to receive an echo packet
  173.       from the remote host.     If the    timeout    is set too low under
  174.       these    conditions, it will appear that    the remote host    is not
  175.       reachable (which is almost the truth).
  176.  
  177.       Reachability doesn't necessarily mean    that the remote    host
  178.       is actually functioning beyond its ability to    echo packets.
  179.  
  180.       Because of a lack of anything    better,    this module uses its
  181.       own routines to pack and unpack ICMP packets.     It would be
  182.       better for a separate    module to be written which understands
  183.       all of the different kinds of    ICMP packets.
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                        (printed 10/23/98)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.      Page 4                        (printed 10/23/98)
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.